qacli view

このサブコマンドは以前の解析による診断の出力を可能にします。

使用方法

view  [-P <directory>] [-K <config name>] [-C <solution-name>] [--cma-project <project-name>] [-R] [-t <ANNSRC|DIAGLST|SUMMARY|SARIF>] [-output-name <filename prefix>] [-o <directory>] [-c] [-a] [-1] [-b] [-Z] [-e] [-F <filelist>] [-X <max-count-filter>] [-S <0|1|2|3|4|5|6|7|8|9>] [-v <0|1|2|3|4|5|6|7|8|9>] [-N <msg-filter>] [-O <msg-filter>] [-D <NONE|SINGLE|DUPLICATE|CMA>] [-M] [-T <ALL|BASELINE|COMMENT|DASHBOARD|INTERACTIVE|MACRO|PRAGMA|VALIDATE>] ...  [-s] [-n] [-r] [-f <format-string>] [-u <rule-format-string>] [-H <header-format-string>] [-x <xml-format-string>] [-d <xml-format-string>] [--xml-indent <indent>] [-i <indent>] [--] [-h] <source-file>

詳しい説明

view　サブコマンドはさまざまな媒体（Text, XML, JSON, HTML）でさまざまな種類(Diagnostic List, Annotated Source, SARIF, Summary)の解析結果の出力をすることを可能にします。フィルタリングによりユーザは何の詳細を、どのファイルから取り出し出力するかを細かくコントロールすることができます。

いくつかの異なる出力の種類が利用可能で、 ‑‑type (‑t)を使用して選ぶことができます。

以下の出力スタイルがあります。

DIAGLST:各ファイルの診断の一覧表を出力します（診断内容を含む）。出力の種類が指定されていない場合、DIAGLST がデフォルトです。詳細については、メッセージリスト (DIAGLST) を参照してください。
ANNSRC: ソースファイルのコピーに診断結果の出力を組込みます。詳細については、注釈付きソースコード (ANNSRC) を参照してください。
SARIF: プロジェクトの全診断結果をSARIF形式の単一ファイルに出力します。詳細については、Static Analysis Results Interchange Format (SARIF) を参照してください。
SUMMARY: プロジェクトの全診断結果の重要度のサマリを単一ファイルに出力します。詳細については、重要度サマリ (SUMMARY) を参照してください。

DIAGLST、ANNSRC、SARIF オプションの使用には適切なライセンスが必要です。

出力は以下に示す形式（または、媒体）です。

HTML: ソースファイルごとに結果を HTML ファイルに出力します。
JSON: 結果をJSON形式で出力します(SARIF出力タイプのみサポート）。
STDERR: 結果を text　で出力します（標準エラー出力）。
STDOUT: 結果を text　で出力します（標準出力）。
XML: ソースファイルごとに結果を XML ファイルに出力します。

まったく制限のないライセンスをお持ちの場合は、コマンドラインで結果を表示したり、結果をファイルに出力したりすることができます。

オリジナルのソースは「読取りのみ」で、いかなる状況下でも、コマンドの如何によらず変更および、変更日時がかわることはありません。

オプションの短縮形は次のように連続記述することができます。例: qacli view ‑P <directory> ‑m STDOUT ‑rs

オプション

名前、短縮形	デフォルト	説明
`‑‑collate‑output, ‑c`		結果を出力するときには、ソースコードのツリー構造を反映するのではなく、すべての出力を単一のディレクトリに集めます。重複しているファイルは上書きされず、そのファイル名は元のファイル名に一意的な番号を追加したものになります。
`‑‑config, ‑K`		複数の設定を持つプロジェクトに対しどの設定を使用するかを指定します。指定がない場合は、デフォルトが使用されます。
`‑‑cma‑solution, ‑‑C`		クロスモジュール解析(CMA)ソリューションを表示するための名前を指定します。このオプションは、ソリューションで関与しているすべての Perforce QAC が表示されることを意味します。解析（CMAソリューションの最初のPerforce QACプロジェクトがデフォルトで使用されます）の結果を表示するためのプロジェクトを指定するには、`‑‑qaf‑project` オプションを使用してください。
`‑‑embed‑header‑messages, ‑e`		ヘッダファイルからソースコードへの組み込み診断（注釈付きソースコードの出力のみ）です。マルチプロジェクトＣＭＡソルーション (`‑C`) は、現在サポートされていません。
`‑‑files, ‑F`		結果を表示することができるファイルのリストを含むファイルのパスを指定します。指定がない場合、プロジェクトに含まれているすべてのファイルの結果が表示されます。
`‑‑format, ‑f`		診断の表示フォーマットを指定します。詳細については、診断ストリングのフォーマットを参照してください。デフォルトのフォーマット文字列: `%F(%l,%c): %?u==0%(%?h%(Err%:Msg%)%:-->%)(%G:%N) %R(%u, )%t%?v%(\n%v%)` 注釈付きソースコード（STDOUTおよびSTDERR）: `%?C%(%^%)%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(%N) %R(%u, )%t%?v%(\n%v%)` 注釈付きソースコード(HTML): `%?C%(%^%)%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(<a href="file://%H">%p-%N</a>) %R(%u, )%t%?v%(<br/>%v%)` SARIFの出力ではフォーマット文字列は空です。
`‑‑header‑format, ‑H`		ヘッダファイルの診断結果の表示形式を指定します。内容は`‑‑format`と同じです。`‑‑embed‑header‑messages` が指定されているときのみ使用します。値が与えられていないけれども、 `‑‑format` への値がある場合、ヘッダ形式としてその値が使用されます。ヘッダおよび `‑‑format` 両方の値がない場合、以下のデフォルト値が使用されます。注釈付きソースコード（STDOUTおよびSTDERR）には: `%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(%N) %R(%u, )%t%?v%(\n%v%)` 注釈付きソースコード(HTML)には: `%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(<a href="file://%H">%p-%N</a>) %R(%u, )%t%?v%(<br/>%v%)` 注釈付きソースコード(XML)には: `%l%c%n%t`
`‑‑help, ‑h`		使用方法の情報を表示し、終了します。
`‑‑ignore‑rest, ‑‑`		このフラグ以降のラベルの付いた引数をすべて無視します。
`‑‑include‑zero‑headers, ‑Z`		デフォルトですべてのソースファイルが出力されますが、ゼロ以外の診断を伴うヘッダのみが表示されます。このオプションは診断の件数に関係なくすべてのソースおよび、ヘッダファイルを表示します。
`‑‑indent, ‑i`	-1　または　0	インデントの各レベルの出力に適用するスペースまたは、タブの数を設定します（XMLおよび、JSON）。スペースには正の数字を、タブには負の数字を使用します。 XMLのデフォルト値は－1、JSONのデフォルト値は 0です。
`‑‑max‑count, ‑X`		メッセージが表示される回数を制限します。デフォルトの0は、無制限が適用されることを示しています。
`‑‑max‑severity, ‑v`		設定されている重要度よりも高い重要度のメッセージをフィルタリングします。このオプションは指定された重要度の範囲内または、特定の重要度のメッセージのみを出力するために　`--min-severity`　オプションと併用することができます。9を指定することができますが、何もフィルタリングしません。
`‑‑min‑severity, ‑S`		設定されている重要度よりも低い重要度のメッセージをフィルタリングします。このオプションは指定された重要度の範囲内または、特定の重要度のメッセージのみを出力するために　`--max-severity`　オプションと併用することができます。0を指定することができますが、何もフィルタリングしません。
`‑‑medium, ‑m`		結果を表示する媒体を指定します。通常のライセンス規定により結果の表示が制限されます。JSON 出力はSARIFの形式のみです。
`‑‑multi‑homed‑format, ‑D`		CMAからの診断結果など、multi-homed (homeless)　の診断を表示するのに使用する形式を指定します。使用可能な値: NONE: multi-homed (homeless)　の診断を表示しない（デフォルト） DUPLICATE: 各ロケーションに各診断を複製する SINGLE: 単一ロケーションに各診断を出力するただし、組込まれたヘッダを除くSUMMARY &　DIAGLST　 CMA: CMA 'file'に出力。SUMMARY のみ
`‑‑nomsg, ‑N`		指定したメッセージの表示を抑止します。メッセージ番号は、下の例のように、個々に指定することも、リストもしくは範囲の形で、または両者を組み合わせて指定することもできます。 `‑‑nomsg 2356 ‑‑nomsg 1234,1236,1240 ‑‑nomsg 2111,2200‑2300`
`‑‑no‑line‑numbers, ‑b`		これを指定すると、行番号を出力しません（ＸＭＬを除く注釈付きソースコードの出力のみ）。
`‑‑no‑header‑messages, ‑n`		これを指定すると、ヘッダファイルからの診断を表示しません。
`‑‑one‑line‑only, ‑1`		関連した診断メッセージのあるソースコードのみを出力します（注釈付きソースコードの出力のみ）。
`‑‑only, ‑O`		指定された警告メッセージのみが表示さされます。メッセージ番号は、下の例のように、個々に指定することも、リストもしくは範囲の形で、または両者を組み合わせて指定することもできます。 `‑‑only 2356 ‑‑only 1234,1236,1240 ‑‑only 2111,2200‑2300`
`‑‑output‑name`		`‑t SUMMARY ‑m XML` または `‑t SARIF ‑m JSON` などファイル名に接頭辞をつけ、単一のファイルを生成するコマンドに使用します。これによりファイル名のカスタマイズをすることができます。
`‑‑output‑path, ‑o`		出力されたファイルを格納するため、書き込みアクセス権限を持つ既存のディレクトリへのパスを指定します。このオプションは、媒体のオプションが HTML、XML またはJSONに設定されている場合のみ有効になります。重複しているファイルは上書きされず、そのファイル名は元のファイル名に一意的な番号を追加したものになります。
`‑‑qaf‑project, ‑P`		結果を表示するため、有効な Perforce QAC プロジェクトへのパスを指定します。
`‑‑relative‑paths, ‑R`		これを指定すると、ソースファイルはソースルートフォルダへの相対部分のみを表示します。
`‑‑rules, ‑r`		表示されているメッセージごとに、メッセージにマップピングされているルールのテキストを表示します。このオプションは`‑‑format`文字列パラメータに`%r` または`%v` が含まれている必要があります。 `‑‑format` オプションが指定されていない場合は、デフォルトが使用されます。使用する値の詳細については、 ‑‑format, ‑f を参照してください。
`‑‑rules‑format, ‑u`		各ルール違反の表示フォーマットを指定します。このストリングにより定義される出力、すなわち各ルール違反は診断ストリングの出力に追加されます（`--format` 　オプションまたは、デフォルトフォーマットストリングに基づき）。詳細については、ルール違反ストリングのフォーマットを参照してください。
`‑‑suppression‑filter, ‑r`		抑止された診断メッセージのどれをフィルタに通すかを指定します。使用可能なオプションは: `ALL`, `BASELINE`, `COMMENT`, `DASHBOARD`, `INTERACTIVE`, `MACRO`, `PRAGMA`, and `VALIDATE`です。フォーマット指定子　'抑止の理由'(`%j`) は、ユーザがこのオプションを選択した場合のみ読込まれます。 `DASHBOARD` および、`VALIDATE` は`INTERACTIVE`と同義とです。
`‑‑type, ‑t`	DIAGLST	以下に結果を表示する形式を指定します。 ANNSRC: 注釈付きソースコードの一覧 DIAGLST: 診断メッセージリスト（デフォルト） SARIF: 業界標準の SARIF 形式 SUMMARY: 各重要度レベルの詳細な診断のサマリテーブル `DIAGLST`、`ANNSRC`、`SARIF` オプションの使用には適切なライセンスが必要です。
`‑‑xml‑format, ‑x`		ユーザマニュアルに記載されているように、XMLの出力が要請されると要素のデフォルト設定を常に出力します。 `xml‑format` ストリングに出力したいフィールドを追加することで、各診断に特定のフィールドを追加して出力することもできます。使用可能な指定子は `‑‑format` ストリング内のフィールドのサブセットです。詳細は、XMLの内容を参照してください。
`‑‑xml‑header‑format, ‑d`		ヘッダファイル用に出力する必要があるXMLの要素を指定します。内容は`‑‑xml‑format`と同じです。 `‑‑embed‑header‑messages` が指定されているときのみ使用します。値が与えられていないけれども `‑‑xml‑format` への値がある場合、ヘッダ形式としてその値が使用されます。 `‑‑xml‑header‑format` および `‑‑xml‑format` 両方が使用されない場合、デフォルト値 `%l%c%n%t`が使用されます。全フィールドを出力する場合は、以下のようにワイルドカードを使用してください:`‑‑xml‑header‑format="*"`

例

このセクションではすべての出力のタイプに共通のオプションについて説明します。特定のスタイルに固有なオプションに対する情報については、このセクションの後にあるサブトピックで説明されています。

Perforce QAC プロジェクトの結果を標準出力するには、以下のコマンドを実行します。

qacli view -P <directory> --medium STDOUT

標準エラーに出力する場合は、上記のコマンドのSTDOUT を STDERR に置き換えます。

‑‑medium オプションの引数を HTML、XML または、JSONに設定すると、ディレクトリを指定できます。ファイルはそのディレクトリに出力されます。

qacli view -P <directory> -m HTML --output-path <directory>

ディレクトリは既存していなければなりません。そして出力はソースファイルのディレクトリの構造を反映します。階層を減らし単一のフォルダに出力を生成するには、‑‑collate‑output (‑c)を追加してください。重複しているファイルは上書きされず、そのファイル名は元のファイル名に一意的な番号を追加したものになります。例:

foo.txt foo(1).txt foo(2).txt

ルール情報をそれぞれの (サブメッセージではなく) メインメッセージとともに表示する場合は、以下のコマンドを実行します。

qacli view -P <directory> -m STDOUT --rules

‑‑rules (‑r) オプションは ‑‑format文字列パラメータに%r または %v を含める必要があります。詳細については、デフォルトフォーマットストリングを参照してください。

Multi-homedメッセージ（特定のプロジェクトファイルではなく、複数のロケーションに生成されるメッセージ）は、 ‑‑multi‑homed‑format, ‑D オプションを使用し、いくつかのフォーマットで出力することが可能です。

メッセージリスト (DIAGLST)

これはデフォルトの出力形式で、サブ診断を含む診断のリストを生成します。出力の形式は、‑‑format オプションにより制御されます。 For information on how to alter this, refer toこのオプションの詳細については、診断ストリングのフォーマットを参照してください。現在のディレクトリにプロジェクトのデフォルト出力を生成するときには、以下のようなコマンドを使用します。

qacli view -m STDOUT -P .

このコマンドの出力は以下の例のようになります。

// ======= Results for /home/katie_mac/.config/Perforce/QAC-
2021.2/samples/sample_inspect_c-2021.2/src/inspect.c
/home/katie_mac/.config/Perforce/QAC-2021.2/samples/sample_inspect_c2021.2/src/inspect.c(0,1): Msg(2:0790) この翻訳単位の中で浮動小数点型が使用されています。
/home/katie_mac/.config/Perforce/QAC-2021.2/samples/sample_inspect_c-
2021.2/src/inspect.c(1,9): Msg(2:4600) マクロ 'NULL' は'<stddef.h>'内でも定義されています。
...

注釈付きソースコード (ANNSRC)

診断をオリジナルのソースコード内（ソースとヘッダ）で注釈コメントとして表示するには、注釈付きソースコード形式を使用します。

qacli view -P <directory> -m HTML --type ANNSRC

関連する診断を含む行のみをソースコードから出力するためには、‑‑one‑line‑only 引数 (‑1) を追加します。

qacli view -P . -m STDOUT -t ANNSRC -1

各ソースファイルおよび、ヘッダに対する個々のエントリを別々に出力するのではなく、 ‑‑embed‑header‑messages 引数 (‑e)を使用して、ヘッダを注釈付きソースコードに組み込むことが可能です。ただし、この形式の出力はマルチプロジェクトCMAソリューションではサポートされていません。

qacli view -P . -m STDOUT -t ANNSRC -e

インクルードファイルの診断の出力では、トップ-レベルの診断のみが表示されます（その下に続くサブ診断は出力されません）。

フォーマットストリングを使用してインクルードファイルの診断をどのような形式で出力するかを指定することもできます。 ‑‑header‑format‑string 引数 (‑H) 内容は、 ‑‑format オプションを使用したときと同様になります。詳細は、診断ストリングのフォーマットを参照してください。

値が与えられていないけれども、‑‑format への値がある場合、ヘッダ形式としてその値が使用されます。 ‑‑header‑format‑string および ‑‑format 両方が使用されない場合、以下のデフォルト値が使用されます。

STDOUT および STDERRへの出力:

%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(%N) %R(%u, )%t%?v%(\n%v%)

HTML への出力:

%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(<a href=\"%H\">%p-%N</a>) %R(%u, )%t%?v%(<br/>%v%)

XML への出力:

%l%c%n%t

これらの値は、‑‑format のデフォルト値とにていますが、先頭の %?C%(%^%) が削除されています。

Static Analysis Results Interchange Format (SARIF)

Static Analysis Results Interchange Format (SARIF)は、静的解析ツールの出力のための業界標準形式です。

標準のバージョン(2.1.0)の出力形式までサポートしています。詳しい標準についてはここ（外部PDF）を参照してください。

SARIF形式での出力には、‑‑type SARIF および ‑‑medium JSONを使用してください。例:

qacli view -P <directory> -m JSON --type SARIF

このコマンドはデフォルト名project.sarifで現在のディレクトリにJSON形式のSARIFファイルを出力します。ファイル名が既に存在する場合、コマンドは失敗します。その場合は、以下のいずれかを試みてください。

ファイルを削除しコマンドを再試行する
‑‑output‑path オプションを使用して異なるディレクトリに出力する
‑‑output‑name オプションを使用して異なるファイル名で出力する
名前に基づく一意的なファイル名を生成するため ‑‑collate‑output オプションを使用する。例： project.sarif が最初に使用されると、次はproject(1).sarif など

他のディレクトリに出力するには、‑‑output‑pathを使用します。例:

qacli view -P <directory> -m JSON --type SARIF --output-path ../frodo

特定の名前の付いたファイルに出力する場合は、 ‑‑output‑nameを使用します。例:

qacli view -P <directory> -m JSON --type SARIF --output-name My_Sarif_File

適切な拡張子 (.sarif) は自動的に加えられます。出力ファイルの厳密な位置と名前を指示するために、‑‑output‑path 、‑‑output‑name の両方を同時に使用することができます。

SARIFファイルはJSON形式を基にしており、非常に大きなファイルになる可能性があります。ファイルは自動的に一番効率的な表示を出力します。すなわち、、最低限のスペース付けと改行でちょっと見ただけでは判読が容易ではありません。そのため、JSON　beautifier　を介して出力することが望ましいでしょう。 Python　にデフォルトで付随しているものを含めいくつかの　JSON　beautifier　があります。例:

python -m json.tool project.sarif > project_formatted.sarif

Linux および、WindowsでのSARIFの内容を表示するビューアは、様々なプロバイダにより提供されています。無償のビューアはここ（外部リンク）で入手することができます。

標準は、厳密に規定されているので、viewコマンドに利用可能なオプションの多く、例えば ‑‑format オプションなど（主に形式に関するもの）が使用できません。 SARIF出力では、デフォルトは空です。すなわち、カスタムのフォーマット文字列は生成されません。明示的にフォーマット文字列を使用することができますが、SARIFのフィールドに明白なマッピングがないため、 “formattedString”と呼ばれるSARIFの“Property Bag”に出力されます。カスタマイズの設定なしで、SARIFリーダがこのフォーマット文字列を表示することはないでしょう。

重要度サマリ (SUMMARY)

プロジェクトの簡潔な重要度サマリの出力には、‑‑type SUMMARYを使用します。例:

qacli view -P <directory> -m STDOUT --type SUMMARY

このコマンドで、コンソールにサマリを出力しますが、必要に応じてファイルに出力先を変更することができます。

もちろんHTMLファイル、XMLファイルへ出力することもできます。デフォルトのファイル名は、 severity_summary.xml (または .html) で、現在使用中の作業ディレクトリに出力されます。

他のディレクトリに出力するには、 ‑‑output‑pathを使用します。例:

qacli view -P <directory> -m XML --type SUMMARY --output-path ../frodo

特定の名前の付いたファイルに出力する場合は、‑‑output‑nameを使用します。例:

qacli view -P <directory> -m XML --type SUMMARY --output-name My_Sev_Summary

適切な拡張子 (.xml または .html) は自動的に加えられます。出力ファイルの厳密な位置と名前を指示するために‑‑output‑path 、‑‑output‑name の両方を同時に使用することができます。

XML形式の出力には、出力形式を記述する追加のスキーマも生成されます。このファイル名は、cli_view_severity_summary.xsdです。

マルチプロジェクトCMAソリューションには、各プロジェクトに対し１つのファイルが生成されます。最初のファイル名は、severity_summary.xml (または.html)、2番目のファイル名は、 severity_summary(1).xml となります。